Loader Widget

Categories: Widgets

Loader Widgetversion added: 1.2

Description: Handles the task of displaying the loading dialog when jQuery Mobile pulls in content via Ajax.

QuickNavExamples

Options

Methods

Events

The Loader Widget

The loader widget handles the task of displaying the loading dialog when jQuery Mobile pulls in content via Ajax. It can also be displayed manually for custom loading actions using the $.mobile.loading helper method (See the global method docs).

To configure the loading dialog globally the following settings can be defined on its prototype during the mobileinit event.

Below are the defaults:
1
2
3
4
5
6
 
$( document ).on( "mobileinit", function() {
  $.mobile.loader.prototype.options.text = "loading";
  $.mobile.loader.prototype.options.textVisible = false;
  $.mobile.loader.prototype.options.theme = "a";
  $.mobile.loader.prototype.options.html = "";
});

These defaults will only be superseded by the method params object described in the global method docs under $.mobile.loading.

1
2
3
4
5
6
 
$.mobile.loading( "show", {
  text: "foo",
  textVisible: true,
  theme: "z",
  html: ""
});

Options

defaultsType: Boolean

Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the loader with the defaults option specified:

1
 
$( ".selector" ).loader({ defaults: true });

Get or set the defaults option, after initialization:

1
2
3
4
5
 
// getter
var defaults = $( ".selector" ).loader( "option", "defaults" );
 
// setter
$( ".selector" ).loader( "option", "defaults", true );

disabledType: Boolean

Default: false
Disables the loader if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the loader with the disabled option specified:

1
 
$( ".selector" ).loader({ disabled: true });

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// getter
var disabled = $( ".selector" ).loader( "option", "disabled" );
 
// setter
$( ".selector" ).loader( "option", "disabled", true );

htmlType: string

Default: ""
If this is set to a non empty string value, it will be used to replace the entirety of the loader's inner html.
Code examples:

Initialize the loader with the html option specified:

1
 
$( ".selector" ).loader({ html: "<span class="ui-icon ui-icon-loading"><img src="jquery-logo.png" /><h2>is loading for you ...</h2></span>" });

Get or set the html option, after initialization:

1
2
3
4
5
 
// getter
var html = $( ".selector" ).loader( "option", "html" );
 
// setter
$( ".selector" ).loader( "option", "html", "<span class="ui-icon ui-icon-loading"><img src="jquery-logo.png" /><h2>is loading for you ...</h2></span>" );

textType: string

Default: loading
Sets the text of the message.
Code examples:

Initialize the loader with the text option specified:

1
 
$( ".selector" ).loader({ text: "Loading Page..." });

Get or set the text option, after initialization:

1
2
3
4
5
 
// getter
var text = $( ".selector" ).loader( "option", "text" );
 
// setter
$( ".selector" ).loader( "option", "text", "Loading Page..." );

textVisibleType: boolean

Default: false
If true, the text value will be used under the spinner.
Code examples:

Initialize the loader with the textVisible option specified:

1
 
$( ".selector" ).loader({ textVisible: true });

Get or set the textVisible option, after initialization:

1
2
3
4
5
 
// getter
var textVisible = $( ".selector" ).loader( "option", "textVisible" );
 
// setter
$( ".selector" ).loader( "option", "textVisible", true );

textonlyType: boolean

Default: false
If true, the "spinner" image will be hidden when the message is shown.
Code examples:

Initialize the loader with the textonly option specified:

1
 
$( ".selector" ).loader({ textonly: true });

Get or set the textonly option, after initialization:

1
2
3
4
5
 
// getter
var textonly = $( ".selector" ).loader( "option", "textonly" );
 
// setter
$( ".selector" ).loader( "option", "textonly", true );

themeType: String

Default: null, inherited from parent
Sets the color scheme (swatch) for the loader widget. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

This option is also exposed as a data attribute: data-theme="b".

Code examples:

Initialize the loader with the theme option specified:

1
 
$( ".selector" ).loader({ theme: "b" });

Get or set the theme option, after initialization:

1
2
3
4
5
 
// getter
var theme = $( ".selector" ).loader( "option", "theme" );
 
// setter
$( ".selector" ).loader( "option", "theme", "b" );

Methods

checkLoaderPosition()Returns: jQuery (plugin only)

Check position of loader to see if it appears to be "fixed" to center.
  • This method does not accept any arguments.
Code examples:

Invoke the checkLoaderPosition method:

1
 
$( ".selector" ).loader( "checkLoaderPosition" );

fakeFixLoader()Returns: jQuery (plugin only)

For non-fixed supporting browsers. Position at y center (if scrollTop supported), above the activeBtn (if defined), or just 100px from top.
  • This method does not accept any arguments.
Code examples:

Invoke the fakeFixLoader method:

1
 
$( ".selector" ).loader( "fakeFixLoader" );

hide()Returns: jQuery (plugin only)

Hide the loader widget
  • This method does not accept any arguments.
Code examples:

Invoke the hide method:

1
 
$( ".selector" ).loader( "hide" );

loading()Returns: jQuery (plugin only)

Show or hide the loader message, which is configurable via $.mobile.loader prototype options as described in the widget docs or can be controlled via a params object.
  • This method does not accept any arguments.
Code examples:

Invoke the loading method:

1
 
$( ".selector" ).loader( "loading" );

resetHtml()Returns: jQuery (plugin only)

  • This method does not accept any arguments.
Code examples:

Invoke the resetHtml method:

1
 
$( ".selector" ).loader( "resetHtml" );

show()Returns: jQuery (plugin only)

  • This method does not accept any arguments.
Code examples:

Invoke the show method:

1
 
$( ".selector" ).loader( "show" );

Events

create( event, ui )Type: loadingcreate

Triggered when a loader widget is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the loader with the create callback specified:

1
2
3
 
$( ".selector" ).loader({
  create: function( event, ui ) {}
});

Bind an event listener to the loadingcreate event:

1
 
$( ".selector" ).on( "loadingcreate", function( event, ui ) {} );

Example:

Loader Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>loader demo</title>
  <link rel="stylesheet" href="http://code.jquery.com/mobile/1.4.4/jquery.mobile-1.4.4.min.css">
  <script src="http://code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="http://code.jquery.com/mobile/1.4.4/jquery.mobile-1.4.4.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div role="main" class="ui-content">
    <div data-role="controlgroup">
      <button class="show-page-loading-msg" data-theme="b" data-textonly="false" data-textvisible="false" data-msgtext="" data-icon="arrow-r" data-iconpos="right">Default loader</button>
      <button class="show-page-loading-msg" data-theme="b" data-textonly="true" data-textvisible="true" data-msgtext="Text only loader" data-icon="arrow-r" data-iconpos="right">Text only</button>
      <button class="show-page-loading-msg" data-theme="b" data-textonly="false" data-textvisible="true" data-msgtext="Loading theme a" data-icon="arrow-r" data-iconpos="right">Theme a</button>
      <button class="show-page-loading-msg" data-theme="a" data-textonly="false" data-textvisible="true" data-msgtext="Loading theme b" data-icon="arrow-r" data-iconpos="right">Theme b</button>
      <button class="show-page-loading-msg" data-theme="b" data-textonly="true" data-textvisible="true" data-msgtext="Custom Loader" data-icon="arrow-r" data-html="<span class='ui-bar ui-overlay-a ui-corner-all'><img src='../_assets/images/jquery-logo.png' /><h2>is loading for you ...</h2></span>" data-iconpos="right">Custom HTML</button>
      <button class="hide-page-loading-msg" data-icon="delete" data-iconpos="right">Hide</button>
    </div>
  </div>
</div>
 
<script>
$(document).on( "click", ".show-page-loading-msg", function() {
  var $this = $( this ),
  theme = $this.jqmData( "theme" ) || $.mobile.loader.prototype.options.theme,
  msgText = $this.jqmData( "msgtext" ) || $.mobile.loader.prototype.options.text,
  textVisible = $this.jqmData( "textvisible" ) || $.mobile.loader.prototype.options.textVisible,
  textonly = !!$this.jqmData( "textonly" );
  html = $this.jqmData( "html" ) || "";
$.mobile.loading( 'show', {
  text: msgText,
  textVisible: textVisible,
  theme: theme,
  textonly: textonly,
  html: html
  });
})
.on( "click", ".hide-page-loading-msg", function() {
  $.mobile.loading( "hide" );
});
</script>
 
</body>
</html>

Demo: